{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "# MCMC Sampling" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Overview\n", "\n", "Stan's MCMC sampler implements the Hamiltonian Monte Carlo (HMC) algorithm and its adaptive variant\n", "the no-U-turn sampler (NUTS).\n", "It creates a set of draws from the posterior distribution of the model conditioned on the data,\n", "allowing for exact Bayesian inference of the model parameters.\n", "Each draw consists of the values for all parameter, transformed parameter, and\n", "generated quantities variables, reported on the constrained scale.\n", "\n", "The [CmdStanModel sample](https://mc-stan.org/cmdstanpy/api.html#cmdstanpy.CmdStanModel.sample) method\n", "wraps the CmdStan [sample](https://mc-stan.org/docs/cmdstan-guide/mcmc_config.html#running-the-sampler) method.\n", "Underlyingly, the CmdStan outputs are a set of per-chain Stan CSV files.\n", "In addition to the resulting sample, reported as one row per draw,\n", "the Stan CSV files encode information about the inference engine configuration\n", "and the sampler state.\n", "The NUTS-HMC adaptive sampler algorithm also outputs the per-chain\n", "HMC tuning parameters `step_size` and `metric`.\n", "\n", "The `sample` method returns a [CmdStanMCMC](https://mc-stan.org/cmdstanpy/api.html#cmdstanmcmc) object,\n", "which provides access to the disparate information from the Stan CSV files.\n", "Accessor functions allow the user\n", "to access the sample in whatever data format is needed for further analysis,\n", "either as tabular data (i.e., in terms of the per-chain CSV file rows and columns),\n", "or as structured objects which correspond to the variables in the Stan model\n", "and the individual diagnostics produced by the inference method.\n", "\n", "\n", "- The [stan_variable](https://mc-stan.org/cmdstanpy/api.html#cmdstanpy.CmdStanMCMC.stan_variable) and\n", "[stan_variables](https://mc-stan.org/cmdstanpy/api.html#cmdstanpy.CmdStanMCMC.stan_variables) methods \n", "return a Python [numpy.ndarray](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray)\n", "containing all draws from the sample where the structure of each draw corresponds to the structure of the\n", "Stan variable.\n", "\n", "- The [draws](https://mc-stan.org/cmdstanpy/api.html#cmdstanpy.CmdStanMCMC.draws) method returns the sample as either a 2-D or 3-D numpy.ndarray.\n", "\n", "- The [draws_pd](https://mc-stan.org/cmdstanpy/api.html#cmdstanpy.CmdStanMCMC.draws_pd) method returns the entire sample or selected variables as a pandas.DataFrame.\n", "\n", "- The [draws_xr](https://mc-stan.org/cmdstanpy/api.html#cmdstanpy.CmdStanMCMC.draws_xr) method returns a structured Xarray dataset over the Stan model variables.\n", "\n", "- The [method_variables](https://mc-stan.org/cmdstanpy/api.html#cmdstanpy.CmdStanMCMC.method_variables) returns a\n", "Python dict over all sampler method variables.\n", "\n", "\n", "In addition, the `CmdStanMCMC` object has accessor methods for\n", "\n", "- The per-chain HMC tuning parameters `step_size` and `metric` \n", "\n", "- The CmdStan run configuration and console outputs\n", "\n", "- The mapping between the Stan model variables and the corresponding CSV file columns." ] }, { "attachments": {}, "cell_type": "markdown", "metadata": {}, "source": [ "### Notebook prerequisites\n", "\n", "\n", "CmdStanPy displays progress bars during sampling via use of package [tqdm](https://github.com/tqdm/tqdm).\n", "In order for these to display properly in a Jupyter notebook, you must have the \n", "[ipywidgets](https://ipywidgets.readthedocs.io/en/latest/index.html) package installed.\n", "For more information, see the the\n", "[installation instructions](https://ipywidgets.readthedocs.io/en/latest/user_install.html#), \n", "also [this tqdm GitHub issue](https://github.com/tqdm/tqdm/issues/394#issuecomment-384743637)." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Fitting the model and data\n", "\n", "In this example we use the CmdStan example model\n", "[bernoulli.stan](https://github.com/stan-dev/cmdstanpy/blob/master/test/data/bernoulli.stan)\n", "and data file\n", "[bernoulli.data.json](https://github.com/stan-dev/cmdstanpy/blob/master/test/data/bernoulli.data.json>).\n", "\n", "We instantiate a `CmdStanModel` from the Stan program file" ] }, { "cell_type": "code", "execution_count": 5, "metadata": {}, "outputs": [], "source": [ "import os\n", "from cmdstanpy import CmdStanModel\n", "\n", "# instantiate, compile bernoulli model\n", "model = CmdStanModel(stan_file='bernoulli.stan')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "By default, the model is compiled during instantiation. The compiled executable is created in the same directory as the program file. If the directory already contains an executable file with a newer timestamp, the model is not recompiled.\n", "\n", "We run the sampler on the data using all default settings: 4 chains, each of which runs 1000 warmup and sampling iterations." ] }, { "cell_type": "code", "execution_count": 6, "metadata": {}, "outputs": [ { "name": "stderr", "output_type": "stream", "text": [ "16:17:55 - cmdstanpy - INFO - CmdStan start processing\n" ] }, { "data": { "application/vnd.jupyter.widget-view+json": { "model_id": "9f05124c597846069d49180ff209d8b6", "version_major": 2, "version_minor": 0 }, "text/plain": [ "chain 1 | | 00:00 Status" ] }, "metadata": {}, "output_type": "display_data" }, { "data": { "application/vnd.jupyter.widget-view+json": { "model_id": "041081927b1644c6aa6d0d8b1c2195a0", "version_major": 2, "version_minor": 0 }, "text/plain": [ "chain 2 | | 00:00 Status" ] }, "metadata": {}, "output_type": "display_data" }, { "data": { "application/vnd.jupyter.widget-view+json": { "model_id": "040a168589d940cf9db02d038144de57", "version_major": 2, "version_minor": 0 }, "text/plain": [ "chain 3 | | 00:00 Status" ] }, "metadata": {}, "output_type": "display_data" }, { "data": { "application/vnd.jupyter.widget-view+json": { "model_id": "d24695e07cbe44628dd87ce656daa26a", "version_major": 2, "version_minor": 0 }, "text/plain": [ "chain 4 | | 00:00 Status" ] }, "metadata": {}, "output_type": "display_data" }, { "name": "stdout", "output_type": "stream", "text": [ " " ] }, { "name": "stderr", "output_type": "stream", "text": [ "16:17:56 - cmdstanpy - INFO - CmdStan done processing.\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "\n" ] } ], "source": [ "# run CmdStan's sample method, returns object `CmdStanMCMC`\n", "fit = model.sample(data='bernoulli.data.json')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The `CmdStanMCMC` object records the command, the return code, and the paths to the sampler output csv and console files. The sample is lazily instantiated on first access of either the draws or the HMC tuning parameters, i.e., the step size and metric.\n", "\n", "The string representation of this object displays the CmdStan commands and the location of the output files.\n", "Output filenames are composed of the model name, a timestamp in the form YYYYMMDDhhmmss and the chain id, plus the corresponding filetype suffix, either '.csv' for the CmdStan output or '.txt' for the console messages, e.g. bernoulli-20220617170100_1.csv." ] }, { "cell_type": "code", "execution_count": 7, "metadata": { "scrolled": true }, "outputs": [ { "data": { "text/plain": [ "CmdStanMCMC: model=bernoulli chains=4['method=sample', 'algorithm=hmc', 'adapt', 'engaged=1']\n", " csv_files:\n", "\t/var/folders/db/4jnggnf549s42z50bd61jskm0000gq/T/tmp0w4tqjfy/bernoulli1_4b9oav/bernoulli-20230925161756_1.csv\n", "\t/var/folders/db/4jnggnf549s42z50bd61jskm0000gq/T/tmp0w4tqjfy/bernoulli1_4b9oav/bernoulli-20230925161756_2.csv\n", "\t/var/folders/db/4jnggnf549s42z50bd61jskm0000gq/T/tmp0w4tqjfy/bernoulli1_4b9oav/bernoulli-20230925161756_3.csv\n", "\t/var/folders/db/4jnggnf549s42z50bd61jskm0000gq/T/tmp0w4tqjfy/bernoulli1_4b9oav/bernoulli-20230925161756_4.csv\n", " output_files:\n", "\t/var/folders/db/4jnggnf549s42z50bd61jskm0000gq/T/tmp0w4tqjfy/bernoulli1_4b9oav/bernoulli-20230925161756_0-stdout.txt\n", "\t/var/folders/db/4jnggnf549s42z50bd61jskm0000gq/T/tmp0w4tqjfy/bernoulli1_4b9oav/bernoulli-20230925161756_1-stdout.txt\n", "\t/var/folders/db/4jnggnf549s42z50bd61jskm0000gq/T/tmp0w4tqjfy/bernoulli1_4b9oav/bernoulli-20230925161756_2-stdout.txt\n", "\t/var/folders/db/4jnggnf549s42z50bd61jskm0000gq/T/tmp0w4tqjfy/bernoulli1_4b9oav/bernoulli-20230925161756_3-stdout.txt" ] }, "execution_count": 7, "metadata": {}, "output_type": "execute_result" } ], "source": [ "fit" ] }, { "cell_type": "code", "execution_count": 8, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "draws as array: (1000, 4, 8)\n", "draws as structured object:\n", "\tdict_keys(['theta'])\n", "sampler diagnostics:\n", "\tdict_keys(['lp__', 'accept_stat__', 'stepsize__', 'treedepth__', 'n_leapfrog__', 'divergent__', 'energy__'])\n" ] } ], "source": [ "print(f'draws as array: {fit.draws().shape}')\n", "print(f'draws as structured object:\\n\\t{fit.stan_variables().keys()}')\n", "print(f'sampler diagnostics:\\n\\t{fit.method_variables().keys()}')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Sampler Progress\n", "\n", "Your model make take a long time to fit. The `sample` method provides two arguments:\n", " \n", "- visual progress bar: `show_progress=True`\n", "- stream CmdStan output to the console - `show_console=True`\n", "\n", "By default, CmdStanPy displays a progress bar during sampling, as seen above.\n", "Since the progress bars are only visible while the sampler is running and the bernoulli example model takes no time at all to fit, we run this model for 200K iterations, in order to see the progress bars in action." ] }, { "cell_type": "code", "execution_count": 9, "metadata": {}, "outputs": [ { "name": "stderr", "output_type": "stream", "text": [ "16:17:57 - cmdstanpy - INFO - CmdStan start processing\n" ] }, { "data": { "application/vnd.jupyter.widget-view+json": { "model_id": "1aeb2ebfa927474e9805898637b15c69", "version_major": 2, "version_minor": 0 }, "text/plain": [ "chain 1 | | 00:00 Status" ] }, "metadata": {}, "output_type": "display_data" }, { "data": { "application/vnd.jupyter.widget-view+json": { "model_id": "bccbe3c795f046c791a5e317a6b83376", "version_major": 2, "version_minor": 0 }, "text/plain": [ "chain 2 | | 00:00 Status" ] }, "metadata": {}, "output_type": "display_data" }, { "data": { "application/vnd.jupyter.widget-view+json": { "model_id": "a662703931e649d3866363a1e2e5b201", "version_major": 2, "version_minor": 0 }, "text/plain": [ "chain 3 | | 00:00 Status" ] }, "metadata": {}, "output_type": "display_data" }, { "data": { "application/vnd.jupyter.widget-view+json": { "model_id": "a4cac644b61b47d8bb99aa5041022cf7", "version_major": 2, "version_minor": 0 }, "text/plain": [ "chain 4 | | 00:00 Status" ] }, "metadata": {}, "output_type": "display_data" }, { "name": "stdout", "output_type": "stream", "text": [ " " ] }, { "name": "stderr", "output_type": "stream", "text": [ "16:17:59 - cmdstanpy - INFO - CmdStan done processing.\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "\n" ] } ], "source": [ "fit = model.sample(data='bernoulli.data.json', iter_warmup=100000, iter_sampling=100000, show_progress=True)\n" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "To see the CmdStan console outputs instead of progress bars, specify ``show_console=True``\n", "This will stream all CmdStan messages to the terminal while the sampler is running.\n", "This option will allow you to debug a Stan program using the Stan language `print` statement." ] }, { "cell_type": "code", "execution_count": 10, "metadata": { "tags": [] }, "outputs": [ { "name": "stderr", "output_type": "stream", "text": [ "16:18:00 - cmdstanpy - INFO - Chain [1] start processing\n", "16:18:00 - cmdstanpy - INFO - Chain [1] done processing\n", "16:18:00 - cmdstanpy - INFO - Chain [2] start processing\n", "16:18:00 - cmdstanpy - INFO - Chain [2] done processing\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "Chain [1] method = sample (Default)\n", "Chain [1] sample\n", "Chain [1] num_samples = 1000 (Default)\n", "Chain [1] num_warmup = 1000 (Default)\n", "Chain [1] save_warmup = 0 (Default)\n", "Chain [1] thin = 1 (Default)\n", "Chain [1] adapt\n", "Chain [1] engaged = 1 (Default)\n", "Chain [1] gamma = 0.050000000000000003 (Default)\n", "Chain [1] delta = 0.80000000000000004 (Default)\n", "Chain [1] kappa = 0.75 (Default)\n", "Chain [1] t0 = 10 (Default)\n", "Chain [1] init_buffer = 75 (Default)\n", "Chain [1] term_buffer = 50 (Default)\n", "Chain [1] window = 25 (Default)\n", "Chain [1] algorithm = hmc (Default)\n", "Chain [1] hmc\n", "Chain [1] engine = nuts (Default)\n", "Chain [1] nuts\n", "Chain [1] max_depth = 10 (Default)\n", "Chain [1] metric = diag_e (Default)\n", "Chain [1] metric_file = (Default)\n", "Chain [1] stepsize = 1 (Default)\n", "Chain [1] stepsize_jitter = 0 (Default)\n", "Chain [1] num_chains = 1 (Default)\n", "Chain [1] id = 1 (Default)\n", "Chain [1] data\n", "Chain [1] file = bernoulli.data.json\n", "Chain [1] init = 2 (Default)\n", "Chain [1] random\n", "Chain [1] seed = 42783\n", "Chain [1] output\n", "Chain [1] file = /var/folders/db/4jnggnf549s42z50bd61jskm0000gq/T/tmp0w4tqjfy/bernoullibjig91zd/bernoulli-20230925161800_1.csv\n", "Chain [1] diagnostic_file = (Default)\n", "Chain [1] refresh = 100 (Default)\n", "Chain [1] sig_figs = -1 (Default)\n", "Chain [1] profile_file = profile.csv (Default)\n", "Chain [1] num_threads = 1 (Default)\n", "Chain [1] \n", "Chain [1] \n", "Chain [1] Gradient evaluation took 6e-06 seconds\n", "Chain [1] 1000 transitions using 10 leapfrog steps per transition would take 0.06 seconds.\n", "Chain [1] Adjust your expectations accordingly!\n", "Chain [1] \n", "Chain [1] \n", "Chain [1] Iteration: 1 / 2000 [ 0%] (Warmup)\n", "Chain [1] Iteration: 100 / 2000 [ 5%] (Warmup)\n", "Chain [1] Iteration: 200 / 2000 [ 10%] (Warmup)\n", "Chain [1] Iteration: 300 / 2000 [ 15%] (Warmup)\n", "Chain [1] Iteration: 400 / 2000 [ 20%] (Warmup)\n", "Chain [1] Iteration: 500 / 2000 [ 25%] (Warmup)\n", "Chain [1] Iteration: 600 / 2000 [ 30%] (Warmup)\n", "Chain [1] Iteration: 700 / 2000 [ 35%] (Warmup)\n", "Chain [1] Iteration: 800 / 2000 [ 40%] (Warmup)\n", "Chain [1] Iteration: 900 / 2000 [ 45%] (Warmup)\n", "Chain [1] Iteration: 1000 / 2000 [ 50%] (Warmup)\n", "Chain [1] Iteration: 1001 / 2000 [ 50%] (Sampling)\n", "Chain [1] Iteration: 1100 / 2000 [ 55%] (Sampling)\n", "Chain [1] Iteration: 1200 / 2000 [ 60%] (Sampling)\n", "Chain [1] Iteration: 1300 / 2000 [ 65%] (Sampling)\n", "Chain [1] Iteration: 1400 / 2000 [ 70%] (Sampling)\n", "Chain [1] Iteration: 1500 / 2000 [ 75%] (Sampling)\n", "Chain [1] Iteration: 1600 / 2000 [ 80%] (Sampling)\n", "Chain [1] Iteration: 1700 / 2000 [ 85%] (Sampling)\n", "Chain [1] Iteration: 1800 / 2000 [ 90%] (Sampling)\n", "Chain [1] Iteration: 1900 / 2000 [ 95%] (Sampling)\n", "Chain [1] Iteration: 2000 / 2000 [100%] (Sampling)\n", "Chain [1] \n", "Chain [1] Elapsed Time: 0.004 seconds (Warm-up)\n", "Chain [1] 0.012 seconds (Sampling)\n", "Chain [1] 0.016 seconds (Total)\n", "Chain [1] \n", "Chain [1] \n", "Chain [2] method = sample (Default)\n", "Chain [2] sample\n", "Chain [2] num_samples = 1000 (Default)\n", "Chain [2] num_warmup = 1000 (Default)\n", "Chain [2] save_warmup = 0 (Default)\n", "Chain [2] thin = 1 (Default)\n", "Chain [2] adapt\n", "Chain [2] engaged = 1 (Default)\n", "Chain [2] gamma = 0.050000000000000003 (Default)\n", "Chain [2] delta = 0.80000000000000004 (Default)\n", "Chain [2] kappa = 0.75 (Default)\n", "Chain [2] t0 = 10 (Default)\n", "Chain [2] init_buffer = 75 (Default)\n", "Chain [2] term_buffer = 50 (Default)\n", "Chain [2] window = 25 (Default)\n", "Chain [2] algorithm = hmc (Default)\n", "Chain [2] hmc\n", "Chain [2] engine = nuts (Default)\n", "Chain [2] nuts\n", "Chain [2] max_depth = 10 (Default)\n", "Chain [2] metric = diag_e (Default)\n", "Chain [2] metric_file = (Default)\n", "Chain [2] stepsize = 1 (Default)\n", "Chain [2] stepsize_jitter = 0 (Default)\n", "Chain [2] num_chains = 1 (Default)\n", "Chain [2] id = 2\n", "Chain [2] data\n", "Chain [2] file = bernoulli.data.json\n", "Chain [2] init = 2 (Default)\n", "Chain [2] random\n", "Chain [2] seed = 42783\n", "Chain [2] output\n", "Chain [2] file = /var/folders/db/4jnggnf549s42z50bd61jskm0000gq/T/tmp0w4tqjfy/bernoullibjig91zd/bernoulli-20230925161800_2.csv\n", "Chain [2] diagnostic_file = (Default)\n", "Chain [2] refresh = 100 (Default)\n", "Chain [2] sig_figs = -1 (Default)\n", "Chain [2] profile_file = profile.csv (Default)\n", "Chain [2] num_threads = 1 (Default)\n", "Chain [2] \n", "Chain [2] \n", "Chain [2] Gradient evaluation took 6e-06 seconds\n", "Chain [2] 1000 transitions using 10 leapfrog steps per transition would take 0.06 seconds.\n", "Chain [2] Adjust your expectations accordingly!\n", "Chain [2] \n", "Chain [2] \n", "Chain [2] Iteration: 1 / 2000 [ 0%] (Warmup)\n", "Chain [2] Iteration: 100 / 2000 [ 5%] (Warmup)\n", "Chain [2] Iteration: 200 / 2000 [ 10%] (Warmup)\n", "Chain [2] Iteration: 300 / 2000 [ 15%] (Warmup)\n", "Chain [2] Iteration: 400 / 2000 [ 20%] (Warmup)\n", "Chain [2] Iteration: 500 / 2000 [ 25%] (Warmup)\n", "Chain [2] Iteration: 600 / 2000 [ 30%] (Warmup)\n", "Chain [2] Iteration: 700 / 2000 [ 35%] (Warmup)\n", "Chain [2] Iteration: 800 / 2000 [ 40%] (Warmup)\n", "Chain [2] Iteration: 900 / 2000 [ 45%] (Warmup)\n", "Chain [2] Iteration: 1000 / 2000 [ 50%] (Warmup)\n", "Chain [2] Iteration: 1001 / 2000 [ 50%] (Sampling)\n", "Chain [2] Iteration: 1100 / 2000 [ 55%] (Sampling)\n", "Chain [2] Iteration: 1200 / 2000 [ 60%] (Sampling)\n", "Chain [2] Iteration: 1300 / 2000 [ 65%] (Sampling)\n", "Chain [2] Iteration: 1400 / 2000 [ 70%] (Sampling)\n", "Chain [2] Iteration: 1500 / 2000 [ 75%] (Sampling)\n", "Chain [2] Iteration: 1600 / 2000 [ 80%] (Sampling)\n", "Chain [2] Iteration: 1700 / 2000 [ 85%] (Sampling)\n", "Chain [2] Iteration: 1800 / 2000 [ 90%] (Sampling)\n", "Chain [2] Iteration: 1900 / 2000 [ 95%] (Sampling)\n", "Chain [2] Iteration: 2000 / 2000 [100%] (Sampling)\n", "Chain [2] \n", "Chain [2] Elapsed Time: 0.004 seconds (Warm-up)\n", "Chain [2] 0.012 seconds (Sampling)\n", "Chain [2] 0.016 seconds (Total)\n", "Chain [2] \n", "Chain [2] \n" ] } ], "source": [ "fit = model.sample(data='bernoulli.data.json', chains=2, parallel_chains=1, show_console=True)\n", "\n" ] }, { "cell_type": "markdown", "metadata": { "tags": [] }, "source": [ "## Checking the fit\n", "\n", "The first question to ask of the `CmdStanMCMC` object is: _is this a valid sample from the posterior?_" ] }, { "cell_type": "markdown", "metadata": { "tags": [] }, "source": [ "It is important to check whether or not the sampler was able to fit the model given the data. Often, this is not possible, for any number of reasons.\n", "To appreciate the sampler diagnostics, we use a hierarchical model which, given a small amount of data, encounters difficulty: the centered parameterization of the \n", "\"8-schools\" model (Rubin, 1981).\n", "The \"8-schools\" model is a simple hierarchical model, first developed on a dataset taken from\n", "an experiment was conducted in 8 schools, with only treatment effects and their standard errors reported.\n", "\n", "The Stan model and the original dataset are in files `eight_schools.stan` and `eight_schools.data.json`." ] }, { "cell_type": "markdown", "metadata": { "tags": [] }, "source": [ "**eight_schools.stan**" ] }, { "cell_type": "code", "execution_count": 11, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "data {\n", " int J; // number of schools\n", " array[J] real y; // estimated treatment effect (school j)\n", " array[J] real sigma; // std err of effect estimate (school j)\n", "}\n", "parameters {\n", " real mu;\n", " array[J] real theta;\n", " real tau;\n", "}\n", "model {\n", " theta ~ normal(mu, tau);\n", " y ~ normal(theta, sigma);\n", "}\n", "\n", "\n" ] } ], "source": [ "with open('eight_schools.stan', 'r') as fd:\n", " print(fd.read())" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "**eight_schools.data.json**" ] }, { "cell_type": "code", "execution_count": 12, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "{\n", " \"J\" : 8,\n", " \"y\" : [28,8,-3,7,-1,1,18,12],\n", " \"sigma\" : [15,10,16,11,9,11,10,18],\n", " \"tau\" : 25\n", "}\n", "\n" ] } ], "source": [ "with open('eight_schools.data.json', 'r') as fd:\n", " print(fd.read())" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Because there is not much data, the geometry of posterior distribution is highly curved, \n", "thus the sampler may encounter difficulty in fitting the model.\n", "By specifying the initial seed for the pseudo-random number generator,\n", "we insure that the sampler will have difficulty in fitting this model.\n", "In particular, some post-warmup iterations diverge, resulting in a biased sample.\n", "In addition, some post-warmup iterations hit the maximum allowed treedepth before\n", "the trajectory hits the \"U-turn\" condition of the NUTS algorithm,\n", "in which case the sampler may fail to properly explore the entire posterior.\n", "\n", "These diagnostics are checked for automatically at the end of each run; if problems are detected, a WARNING message is logged." ] }, { "cell_type": "code", "execution_count": 13, "metadata": {}, "outputs": [ { "name": "stderr", "output_type": "stream", "text": [ "16:18:01 - cmdstanpy - INFO - CmdStan start processing\n" ] }, { "data": { "application/vnd.jupyter.widget-view+json": { "model_id": "ffbfef209eb84b64b01cf9c18b42514e", "version_major": 2, "version_minor": 0 }, "text/plain": [ "chain 1 | | 00:00 Status" ] }, "metadata": {}, "output_type": "display_data" }, { "data": { "application/vnd.jupyter.widget-view+json": { "model_id": "d66ab35ce0d54be48ab0aa75da85dccf", "version_major": 2, "version_minor": 0 }, "text/plain": [ "chain 2 | | 00:00 Status" ] }, "metadata": {}, "output_type": "display_data" }, { "data": { "application/vnd.jupyter.widget-view+json": { "model_id": "b138cfcf18334ba88e09e5f2debedd29", "version_major": 2, "version_minor": 0 }, "text/plain": [ "chain 3 | | 00:00 Status" ] }, "metadata": {}, "output_type": "display_data" }, { "data": { "application/vnd.jupyter.widget-view+json": { "model_id": "89e81384e9c14e56a1cb233a8f6f0d27", "version_major": 2, "version_minor": 0 }, "text/plain": [ "chain 4 | | 00:00 Status" ] }, "metadata": {}, "output_type": "display_data" }, { "name": "stdout", "output_type": "stream", "text": [ " " ] }, { "name": "stderr", "output_type": "stream", "text": [ "16:18:01 - cmdstanpy - INFO - CmdStan done processing.\n", "16:18:01 - cmdstanpy - WARNING - Some chains may have failed to converge.\n", "\tChain 1 had 10 divergent transitions (1.0%)\n", "\tChain 2 had 143 divergent transitions (14.3%)\n", "\tChain 3 had 5 divergent transitions (0.5%)\n", "\tChain 4 had 4 divergent transitions (0.4%)\n", "\tChain 4 had 6 iterations at max treedepth (0.6%)\n", "\tUse the \"diagnose()\" method on the CmdStanMCMC object to see further information.\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "\n" ] } ], "source": [ "eight_schools_model = CmdStanModel(stan_file='eight_schools.stan')\n", "eight_schools_fit = eight_schools_model.sample(data='eight_schools.data.json', seed=55157)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "More information on how to address convergence problems can be found at https://mc-stan.org/misc/warnings\n", "\n", "The number of post-warmup divergences and iterations which hit the maximum treedepth can be inspected directly via properties `divergences` and `max_treedepths`." ] }, { "cell_type": "code", "execution_count": 14, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "divergences:\n", "[ 10 143 5 4]\n", "iterations at max_treedepth:\n", "[0 0 0 6]\n" ] } ], "source": [ "print(f'divergences:\\n{eight_schools_fit.divergences}\\niterations at max_treedepth:\\n{eight_schools_fit.max_treedepths}')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Summarizing the sample\n", "\n", "The `summary` method reports the R-hat statistic, a measure of how well the sampler chains have converged." ] }, { "cell_type": "code", "execution_count": 15, "metadata": { "scrolled": true }, "outputs": [ { "data": { "text/html": [ "
\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
MeanMCSEStdDev5%50%95%N_EffN_Eff/sR_hat
lp__-16.475101.3938307.33884-26.342300-17.71920-5.8221427.7228037.872701.12057
mu7.365800.3584415.36980-0.0901576.9870816.39460224.43000306.598001.03328
theta[1]11.020400.6939698.596680.3989029.6709427.12670153.45500209.638001.03967
theta[2]7.445470.2229706.32424-2.1931706.7745818.33640804.499001099.040001.01501
theta[3]5.468140.2301467.65499-7.4367105.2009417.526001106.330001511.380001.00842
theta[4]7.072080.2576626.80149-3.2966206.5840118.50130696.79800951.910001.01756
theta[5]4.596640.1932926.13195-6.0676504.0453714.533601006.390001374.850001.00407
theta[6]5.693260.1990796.77053-5.4029005.3026516.486801156.630001580.090001.00729
theta[7]10.049500.6281187.100790.6752469.1740223.36110127.80000174.591001.03588
theta[8]7.840090.2915268.04207-4.0164207.0073121.58680760.994001039.610001.01463
tau6.603330.5573605.774921.0198505.2141917.68580107.35287146.656921.04858
\n", "
" ], "text/plain": [ " Mean MCSE StdDev 5% 50% 95% \\\n", "lp__ -16.47510 1.393830 7.33884 -26.342300 -17.71920 -5.82214 \n", "mu 7.36580 0.358441 5.36980 -0.090157 6.98708 16.39460 \n", "theta[1] 11.02040 0.693969 8.59668 0.398902 9.67094 27.12670 \n", "theta[2] 7.44547 0.222970 6.32424 -2.193170 6.77458 18.33640 \n", "theta[3] 5.46814 0.230146 7.65499 -7.436710 5.20094 17.52600 \n", "theta[4] 7.07208 0.257662 6.80149 -3.296620 6.58401 18.50130 \n", "theta[5] 4.59664 0.193292 6.13195 -6.067650 4.04537 14.53360 \n", "theta[6] 5.69326 0.199079 6.77053 -5.402900 5.30265 16.48680 \n", "theta[7] 10.04950 0.628118 7.10079 0.675246 9.17402 23.36110 \n", "theta[8] 7.84009 0.291526 8.04207 -4.016420 7.00731 21.58680 \n", "tau 6.60333 0.557360 5.77492 1.019850 5.21419 17.68580 \n", "\n", " N_Eff N_Eff/s R_hat \n", "lp__ 27.72280 37.87270 1.12057 \n", "mu 224.43000 306.59800 1.03328 \n", "theta[1] 153.45500 209.63800 1.03967 \n", "theta[2] 804.49900 1099.04000 1.01501 \n", "theta[3] 1106.33000 1511.38000 1.00842 \n", "theta[4] 696.79800 951.91000 1.01756 \n", "theta[5] 1006.39000 1374.85000 1.00407 \n", "theta[6] 1156.63000 1580.09000 1.00729 \n", "theta[7] 127.80000 174.59100 1.03588 \n", "theta[8] 760.99400 1039.61000 1.01463 \n", "tau 107.35287 146.65692 1.04858 " ] }, "execution_count": 15, "metadata": {}, "output_type": "execute_result" } ], "source": [ "eight_schools_fit.summary()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Sampler Diagnostics\n", "\n", "The `diagnose()` method provides more information about the sample." ] }, { "cell_type": "code", "execution_count": 16, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Processing csv files: /var/folders/db/4jnggnf549s42z50bd61jskm0000gq/T/tmp0w4tqjfy/eight_schoolsz56j88wq/eight_schools-20230925161801_1.csv, /var/folders/db/4jnggnf549s42z50bd61jskm0000gq/T/tmp0w4tqjfy/eight_schoolsz56j88wq/eight_schools-20230925161801_2.csv, /var/folders/db/4jnggnf549s42z50bd61jskm0000gq/T/tmp0w4tqjfy/eight_schoolsz56j88wq/eight_schools-20230925161801_3.csv, /var/folders/db/4jnggnf549s42z50bd61jskm0000gq/T/tmp0w4tqjfy/eight_schoolsz56j88wq/eight_schools-20230925161801_4.csv\n", "\n", "Checking sampler transitions treedepth.\n", "6 of 4000 (0.15%) transitions hit the maximum treedepth limit of 10, or 2^10 leapfrog steps.\n", "Trajectories that are prematurely terminated due to this limit will result in slow exploration.\n", "For optimal performance, increase this limit.\n", "\n", "Checking sampler transitions for divergences.\n", "162 of 4000 (4.05%) transitions ended with a divergence.\n", "These divergent transitions indicate that HMC is not fully able to explore the posterior distribution.\n", "Try increasing adapt delta closer to 1.\n", "If this doesn't remove all divergences, try to reparameterize the model.\n", "\n", "Checking E-BFMI - sampler transitions HMC potential energy.\n", "The E-BFMI, 0.18, is below the nominal threshold of 0.30 which suggests that HMC may have trouble exploring the target distribution.\n", "If possible, try to reparameterize the model.\n", "\n", "Effective sample size satisfactory.\n", "\n", "Split R-hat values satisfactory all parameters.\n", "\n", "Processing complete.\n", "\n" ] } ], "source": [ "print(eight_schools_fit.diagnose())" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Accessing the sampler outputs" ] }, { "cell_type": "code", "execution_count": 17, "metadata": {}, "outputs": [ { "name": "stderr", "output_type": "stream", "text": [ "16:18:09 - cmdstanpy - INFO - CmdStan start processing\n" ] }, { "data": { "application/vnd.jupyter.widget-view+json": { "model_id": "6135a0a7681d41e28c3f83188acb6f2e", "version_major": 2, "version_minor": 0 }, "text/plain": [ "chain 1 | | 00:00 Status" ] }, "metadata": {}, "output_type": "display_data" }, { "data": { "application/vnd.jupyter.widget-view+json": { "model_id": "88fad8d6b2314633a96698e841380b00", "version_major": 2, "version_minor": 0 }, "text/plain": [ "chain 2 | | 00:00 Status" ] }, "metadata": {}, "output_type": "display_data" }, { "data": { "application/vnd.jupyter.widget-view+json": { "model_id": "162d9eec51774f55b92d5e92da31bf1a", "version_major": 2, "version_minor": 0 }, "text/plain": [ "chain 3 | | 00:00 Status" ] }, "metadata": {}, "output_type": "display_data" }, { "data": { "application/vnd.jupyter.widget-view+json": { "model_id": "06c665ed993b4ad5ba2862bb9e444992", "version_major": 2, "version_minor": 0 }, "text/plain": [ "chain 4 | | 00:00 Status" ] }, "metadata": {}, "output_type": "display_data" }, { "name": "stdout", "output_type": "stream", "text": [ " " ] }, { "name": "stderr", "output_type": "stream", "text": [ "16:18:09 - cmdstanpy - INFO - CmdStan done processing.\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "\n" ] } ], "source": [ "fit = model.sample(data='bernoulli.data.json')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Extracting the draws as structured Stan program variables\n", "\n", "Per-variable draws can be accessed as either a numpy.ndarray object\n", "via method `stan_variable` or as an xarray.Dataset object via `draws_xr`." ] }, { "cell_type": "code", "execution_count": 18, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "[0.187637 0.167524 0.454131 ... 0.506709 0.14154 0.333167]\n" ] } ], "source": [ "print(fit.stan_variable('theta'))" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The `stan_variables` method returns a Python `dict` over all Stan variables in the output." ] }, { "cell_type": "code", "execution_count": 19, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "name: theta, shape: (4000,)\n" ] } ], "source": [ "for k, v in fit.stan_variables().items():\n", " print(f'name: {k}, shape: {v.shape}')" ] }, { "cell_type": "code", "execution_count": 20, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "\n", "Dimensions: (draw: 1000, chain: 4)\n", "Coordinates:\n", " * chain (chain) int64 1 2 3 4\n", " * draw (draw) int64 0 1 2 3 4 5 6 7 8 ... 992 993 994 995 996 997 998 999\n", "Data variables:\n", " theta (chain, draw) float64 0.1876 0.1675 0.4541 ... 0.5067 0.1415 0.3332\n", "Attributes:\n", " stan_version: 2.33.0\n", " model: bernoulli_model\n", " num_draws_sampling: 1000\n" ] } ], "source": [ "print(fit.draws_xr('theta'))" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Extracting the draws in tabular format\n", "\n", "The sample can be accessed either as a `numpy` array or a pandas `DataFrame`:" ] }, { "cell_type": "code", "execution_count": 21, "metadata": {}, "outputs": [], "source": [ "import xarray as x" ] }, { "cell_type": "code", "execution_count": 22, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "sample as ndarray: (1000, 4, 8)\n", "first 2 draws, chain 1:\n", "[[-6.89001 0.981831 0.870591 1. 1. 0. 6.89017\n", " 0.187637]\n", " [-7.01004 0.849367 0.870591 2. 3. 0. 8.19459\n", " 0.167524]]\n" ] } ], "source": [ "print(f'sample as ndarray: {fit.draws().shape}\\nfirst 2 draws, chain 1:\\n{fit.draws()[:2, 0, :]}')" ] }, { "cell_type": "code", "execution_count": 23, "metadata": {}, "outputs": [ { "data": { "text/html": [ "
\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
chain__iter__draw__lp__accept_stat__stepsize__treedepth__n_leapfrog__divergent__energy__theta
01.01.01.0-6.890010.9818310.8705911.01.00.06.890170.187637
11.02.02.0-7.010040.8493670.8705912.03.00.08.194590.167524
21.03.03.0-7.816500.8251090.8705911.03.00.08.777060.454131
31.04.04.0-6.789601.0000000.8705912.03.00.07.795960.215159
41.05.05.0-7.217780.9401150.8705912.03.00.07.327700.143557
\n", "
" ], "text/plain": [ " chain__ iter__ draw__ lp__ accept_stat__ stepsize__ treedepth__ \\\n", "0 1.0 1.0 1.0 -6.89001 0.981831 0.870591 1.0 \n", "1 1.0 2.0 2.0 -7.01004 0.849367 0.870591 2.0 \n", "2 1.0 3.0 3.0 -7.81650 0.825109 0.870591 1.0 \n", "3 1.0 4.0 4.0 -6.78960 1.000000 0.870591 2.0 \n", "4 1.0 5.0 5.0 -7.21778 0.940115 0.870591 2.0 \n", "\n", " n_leapfrog__ divergent__ energy__ theta \n", "0 1.0 0.0 6.89017 0.187637 \n", "1 3.0 0.0 8.19459 0.167524 \n", "2 3.0 0.0 8.77706 0.454131 \n", "3 3.0 0.0 7.79596 0.215159 \n", "4 3.0 0.0 7.32770 0.143557 " ] }, "execution_count": 23, "metadata": {}, "output_type": "execute_result" } ], "source": [ "fit.draws_pd().head()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Extracting sampler method diagnostics" ] }, { "cell_type": "code", "execution_count": 24, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "name: lp__, shape: (1000, 4)\n", "name: accept_stat__, shape: (1000, 4)\n", "name: stepsize__, shape: (1000, 4)\n", "name: treedepth__, shape: (1000, 4)\n", "name: n_leapfrog__, shape: (1000, 4)\n", "name: divergent__, shape: (1000, 4)\n", "name: energy__, shape: (1000, 4)\n" ] } ], "source": [ "for k, v in fit.method_variables().items():\n", " print(f'name: {k}, shape: {v.shape}')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Extracting the per-chain HMC tuning parameters" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "adapted step_size per chain\n", "[0.870591 0.97456 1.00695 0.975628]\n", "metric_type: diag_e\n", "metric:\n", "[[0.557946]\n", " [0.469587]\n", " [0.567582]\n", " [0.467572]]\n" ] } ], "source": [ "print(f'adapted step_size per chain\\n{fit.step_size}\\nmetric_type: {fit.metric_type}\\ninverse metric:\\n{fit.inv_metric}')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Extracting the sample meta-data" ] }, { "cell_type": "code", "execution_count": 26, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "sample method variables:\n", "dict_keys(['lp__', 'accept_stat__', 'stepsize__', 'treedepth__', 'n_leapfrog__', 'divergent__', 'energy__'])\n", "\n", "stan model variables:\n", "dict_keys(['theta'])\n" ] } ], "source": [ "print('sample method variables:\\n{}\\n'.format(fit.metadata.method_vars.keys()))\n", "print('stan model variables:\\n{}'.format(fit.metadata.stan_vars.keys()))" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Saving the sampler output files\n", "\n", "The sampler output files are written to a temporary directory which\n", "is deleted upon session exit unless the ``output_dir`` argument is specified.\n", "The ``save_csvfiles`` function moves the CmdStan CSV output files\n", "to a specified directory without having to re-run the sampler.\n", "The console output files are not saved. These files are treated as ephemeral; if the sample is valid, all relevant information is recorded in the CSV files." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Parallelization via multi-threaded processing\n", "\n", "Stan's multi-threaded processing is based on the Intel Threading Building Blocks (TBB) library, which must be linked to by the C++ compiler. To take advantage of this option, you must compile (or recompile) the program with the the C++ compiler option `STAN_THREADS`.\n", "The CmdStanModel object constructor and its `compile` method both have argument `cpp_options`\n", "which takes as its value a dictionary of compiler flags.\n", "\n", "We compile the example model `bernoulli.stan`, this time with arguments `cpp_options` and `compile`, and use the function `exe_info()` to check that the model has been compiled for multi-threading." ] }, { "cell_type": "code", "execution_count": 27, "metadata": {}, "outputs": [ { "name": "stderr", "output_type": "stream", "text": [ "16:18:21 - cmdstanpy - WARNING - CmdStanModel(compile=...) is deprecated and will be removed in the next major version. The constructor will always ensure a model has a compiled executable.\n", "If you wish to force recompilation, use force_compile=True instead.\n", "16:18:21 - cmdstanpy - INFO - compiling stan file /Users/mitzi/github/stan-dev/cmdstanpy/docsrc/users-guide/examples/bernoulli.stan to exe file /Users/mitzi/github/stan-dev/cmdstanpy/docsrc/users-guide/examples/bernoulli\n", "16:18:30 - cmdstanpy - INFO - compiled model executable: /Users/mitzi/github/stan-dev/cmdstanpy/docsrc/users-guide/examples/bernoulli\n" ] }, { "data": { "text/plain": [ "{'stan_version_major': '2',\n", " 'stan_version_minor': '33',\n", " 'stan_version_patch': '0',\n", " 'STAN_THREADS': 'true',\n", " 'STAN_MPI': 'false',\n", " 'STAN_OPENCL': 'false',\n", " 'STAN_NO_RANGE_CHECKS': 'false',\n", " 'STAN_CPP_OPTIMS': 'false'}" ] }, "execution_count": 27, "metadata": {}, "output_type": "execute_result" } ], "source": [ "model = CmdStanModel(stan_file='bernoulli.stan',\n", " cpp_options={'STAN_THREADS': 'TRUE'},\n", " compile='force')\n", "model.exe_info()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Cross-chain multi-threading\n", "\n", "As of version CmdStan 2.28, it is possible to run the NUTS-HMC sampler on\n", "multiple chains from within a single executable using threads.\n", "This has the potential to speed up sampling. It also\n", "reduces the overall memory footprint required for sampling as\n", "all chains share the same copy of data.the input data.\n", "When using within-chain parallelization all chains started\n", "within a single executable can share all the available threads\n", "and once a chain finishes the threads will be reused.\n", "\n", "The sample program argument ``parallel_chains`` takes an integer value which\n", "specifies how many chains to run in parallel.\n", "For models which have been compiled with option `STAN_THREADS` set, all chains are run from\n", "within a single process and the value of the ``parallel_chains`` argument specifies the total number of threads." ] }, { "cell_type": "code", "execution_count": 28, "metadata": {}, "outputs": [ { "name": "stderr", "output_type": "stream", "text": [ "16:18:30 - cmdstanpy - INFO - CmdStan start processing\n" ] }, { "data": { "application/vnd.jupyter.widget-view+json": { "model_id": "14ffefd5499e40b982f50233584783ce", "version_major": 2, "version_minor": 0 }, "text/plain": [ "chain 1 | | 00:00 Status" ] }, "metadata": {}, "output_type": "display_data" }, { "data": { "application/vnd.jupyter.widget-view+json": { "model_id": "c23ec7d12e1a45f8a01ae88133616501", "version_major": 2, "version_minor": 0 }, "text/plain": [ "chain 2 | | 00:00 Status" ] }, "metadata": {}, "output_type": "display_data" }, { "data": { "application/vnd.jupyter.widget-view+json": { "model_id": "a8d8be6bda8547649f134d342615dd87", "version_major": 2, "version_minor": 0 }, "text/plain": [ "chain 3 | | 00:00 Status" ] }, "metadata": {}, "output_type": "display_data" }, { "data": { "application/vnd.jupyter.widget-view+json": { "model_id": "aabbfef36fe04a11bc27d5947afe28dc", "version_major": 2, "version_minor": 0 }, "text/plain": [ "chain 4 | | 00:00 Status" ] }, "metadata": {}, "output_type": "display_data" }, { "name": "stdout", "output_type": "stream", "text": [ " " ] }, { "name": "stderr", "output_type": "stream", "text": [ "16:18:30 - cmdstanpy - INFO - CmdStan done processing.\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "\n" ] } ], "source": [ "fit = model.sample(data='bernoulli.data.json', parallel_chains=4)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Within-chain multi-threading\n", "\n", "The Stan language\n", "[reduce_sum](https://mc-stan.org/docs/stan-users-guide/reduce-sum.html)\n", "function provides within-chain parallelization.\n", "For models which require computing the sum of a number of independent function evaluations,\n", "e.g., when evaluating a number of conditionally independent terms in a log-likelihood,\n", "the `reduce_sum` function is used to parallelize this computation.\n", "\n", "To see how this works, we run the \"reflag\" model, used in the \n", "[reduce_sum minimal example](https://mc-stan.org/users/documentation/case-studies/reduce_sum_tutorial.html) case study.\n", "The Stan model and the original dataset are in files \"redcard_reduce_sum.stan\" and \"redcard.json\"." ] }, { "cell_type": "code", "execution_count": 29, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "functions {\n", " real partial_sum(array[] int slice_n_redcards, int start, int end,\n", " array[] int n_games, vector rating, vector beta) {\n", " return binomial_logit_lpmf(slice_n_redcards | n_games[start : end], beta[1]\n", " + beta[2]\n", " * rating[start : end]);\n", " }\n", "}\n", "data {\n", " int N;\n", " array[N] int n_redcards;\n", " array[N] int n_games;\n", " vector[N] rating;\n", " int grainsize;\n", "}\n", "parameters {\n", " vector[2] beta;\n", "}\n", "model {\n", " beta[1] ~ normal(0, 10);\n", " beta[2] ~ normal(0, 1);\n", " \n", " target += reduce_sum(partial_sum, n_redcards, grainsize, n_games, rating,\n", " beta);\n", "}\n", "\n", "\n" ] } ], "source": [ "with open('redcard_reduce_sum.stan', 'r') as fd:\n", " print(fd.read())" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "As before, we compile the model specifying argument `cpp_options`." ] }, { "cell_type": "code", "execution_count": 30, "metadata": {}, "outputs": [ { "name": "stderr", "output_type": "stream", "text": [ "16:18:30 - cmdstanpy - WARNING - CmdStanModel(compile=...) is deprecated and will be removed in the next major version. The constructor will always ensure a model has a compiled executable.\n", "If you wish to force recompilation, use force_compile=True instead.\n", "16:18:30 - cmdstanpy - INFO - compiling stan file /Users/mitzi/github/stan-dev/cmdstanpy/docsrc/users-guide/examples/redcard_reduce_sum.stan to exe file /Users/mitzi/github/stan-dev/cmdstanpy/docsrc/users-guide/examples/redcard_reduce_sum\n", "16:18:38 - cmdstanpy - INFO - compiled model executable: /Users/mitzi/github/stan-dev/cmdstanpy/docsrc/users-guide/examples/redcard_reduce_sum\n" ] }, { "data": { "text/plain": [ "{'stan_version_major': '2',\n", " 'stan_version_minor': '33',\n", " 'stan_version_patch': '0',\n", " 'STAN_THREADS': 'true',\n", " 'STAN_MPI': 'false',\n", " 'STAN_OPENCL': 'false',\n", " 'STAN_NO_RANGE_CHECKS': 'false',\n", " 'STAN_CPP_OPTIMS': 'false'}" ] }, "execution_count": 30, "metadata": {}, "output_type": "execute_result" } ], "source": [ "redcard_model = CmdStanModel(stan_file='redcard_reduce_sum.stan',\n", " cpp_options={'STAN_THREADS': 'TRUE'},\n", " compile='force')\n", "redcard_model.exe_info()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The `sample` method argument `threads_per_chain` specifies the number of threads allotted to each chain; this corresponds to CmdStan's `num_threads` argument." ] }, { "cell_type": "code", "execution_count": 31, "metadata": {}, "outputs": [ { "name": "stderr", "output_type": "stream", "text": [ "16:18:38 - cmdstanpy - INFO - CmdStan start processing\n" ] }, { "data": { "application/vnd.jupyter.widget-view+json": { "model_id": "4d2a9c60d4a947159bb5bbd42a385438", "version_major": 2, "version_minor": 0 }, "text/plain": [ "chain 1 | | 00:00 Status" ] }, "metadata": {}, "output_type": "display_data" }, { "data": { "application/vnd.jupyter.widget-view+json": { "model_id": "0a5bc048a9e046b98ce91dd4a108bd4b", "version_major": 2, "version_minor": 0 }, "text/plain": [ "chain 2 | | 00:00 Status" ] }, "metadata": {}, "output_type": "display_data" }, { "data": { "application/vnd.jupyter.widget-view+json": { "model_id": "dfe3e157af1b41d9a21a6fee769a0d88", "version_major": 2, "version_minor": 0 }, "text/plain": [ "chain 3 | | 00:00 Status" ] }, "metadata": {}, "output_type": "display_data" }, { "data": { "application/vnd.jupyter.widget-view+json": { "model_id": "1374d6284f2e45379a536ea3b2f3b7cb", "version_major": 2, "version_minor": 0 }, "text/plain": [ "chain 4 | | 00:00 Status" ] }, "metadata": {}, "output_type": "display_data" }, { "name": "stdout", "output_type": "stream", "text": [ " " ] }, { "name": "stderr", "output_type": "stream", "text": [ "16:19:23 - cmdstanpy - INFO - CmdStan done processing.\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "\n" ] } ], "source": [ "redcard_fit = redcard_model.sample(data='redcard.json', threads_per_chain=4)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The number of threads to use is passed to the model exe file by means of the shell environment variable `STAN_NUM_THREADS`.\n", "\n", "On my machine, which has 4 cores, all 4 chains are run in parallel from within a single process.\n", "Therefore, the total number of threads used by this process will be `threads_per_chain` * `chains`.\n", "To check this, we examine the shell environment variable `STAN_NUM_THREADS`." ] }, { "cell_type": "code", "execution_count": 32, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "'16'" ] }, "execution_count": 32, "metadata": {}, "output_type": "execute_result" } ], "source": [ "os.environ['STAN_NUM_THREADS']" ] } ], "metadata": { "kernelspec": { "display_name": "Python 3 (ipykernel)", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.9.16" } }, "nbformat": 4, "nbformat_minor": 4 }